home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / arexx-scripts / dopus / dopuslharexx / docs / dopuslharexx.doc < prev    next >
Encoding:
Text File  |  1994-01-03  |  18.1 KB  |  606 lines
  1.  
  2. DOpusLhARexx Documentation
  3.  
  4.  
  5.                     Documentation for DOpusLhARexx 40.1
  6.                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  7.                          Date: January 3, 1994
  8.  
  9.                         © 1994 Nirvana Software
  10.  
  11.                          Author: Geoff Seeley 
  12.  
  13.  
  14.    Overview         - About the archive.
  15.    Copyrights       - Important information.
  16.    Acknowledgments  - Who made it possible.
  17.    Installation     - Setting up on your system.
  18.    Known Bugs       - What doesn't work
  19.    Program History  - What was done to fix the above :-)
  20.    ToDos            - What I would like to do
  21.  
  22.  
  23.  
  24. Preface
  25.  
  26.  
  27.  Preface
  28.  ~~~~~~~
  29.  
  30.    I finally got around to purchasing a copy of Directory Opus recently,
  31.    I'm just sorry I didn't do it sooner.
  32.  
  33.    Anyway, the files contained in this archive are a direct result of my
  34.    "seeing what this baby can do" and hacking around with DOpus. I 
  35.    noticed that a few people on the InterNet were impressed with the ability
  36.    of certain other directory utilities that allowed a user to view an LhA
  37.    archive like a set of files. So...
  38.  
  39.    DOpusLhARexx is a set of ARexx scripts for Directory Opus that will allow
  40.    you to view LhA archive files in a DOpus window and extract/delete/add
  41.    one or more files to/from the archive.
  42.  
  43.    The DOpusLhARexx programs were developed and tested using the following
  44.    programs. Your mileage may vary with other versions....
  45.  
  46.       LhA   v1.38
  47.       DOpus v4.11
  48.  
  49.  
  50.  
  51. Copyrights
  52.  
  53.  
  54.  Copyrights
  55.  ~~~~~~~~~~
  56.  
  57.  
  58.    The code within DOpusLhARexx is freely distributable and may not be 
  59.    sold for profit, however the code remains:
  60.  
  61.                Copyrighted © 1994 (All rights reserved)
  62.                 by Nirvana Software and Geoff Seeley.
  63.  
  64.    DOpusLhARexx may be included in public domain libraries such as Fred
  65.    Fish's "Amiga Freely Redistributable Library" as long as no profit 
  66.    is made from these programs and no files in the archive are modified
  67.    in any way.
  68.  
  69.    DOpusLhARexx may also be included on the AmiNet CD-ROM.
  70.  
  71.    If you *must* make improvements to these programs, please oh please,
  72.    either send them to me for inclusion in a future release, or at least
  73.    upload them to your nearest AmiNet archive site so that the Amiga
  74.    community can benefit and enjoy.
  75.  
  76.    No warrantees are expressed or implied for these programs. Use them at
  77.    your own risk.
  78.  
  79.    Directory Opus is copyrighted by Jonathan Potter and sold by
  80.    Inovatronics, Inc.
  81.  
  82.    ARexx is a trademark of the Wishful Thinking Developement Corp. and
  83.    William S. Hawes.
  84.  
  85.    LhA is copyrighted by Stefan Boberg.
  86.  
  87.    AmigaGuide, Commodore's Installer and Workbench are copyrighted trademarks
  88.    of Commodore-Amiga, Inc.
  89.  
  90.  
  91.  
  92. Acknowledgements
  93.  
  94.  
  95.  Acknowledgements
  96.  ~~~~~~~~~~~~~~~~
  97.  
  98.  
  99.    The following people and groups made these programs possible.
  100.  
  101.    Thanks go to:
  102.  
  103.  
  104.       Jonathan Potter for creating the indispensable Directory Opus program.
  105.  
  106.       Bill Hawes for implementing Rexx for the Amiga, and Commodore for
  107.       including it into the OS.
  108.  
  109.       Billy Gates and MicroSoft for creating DOS6, Windows, Word, Excel, etc.
  110.       which convince me each and every work day that the Commodore Amiga is
  111.       *the* one and *only* platform to program/use...
  112.  
  113.  
  114.  
  115. Installation
  116.  
  117.  
  118.  Installation
  119.  ~~~~~~~~~~~~
  120.  
  121.    Sorry, no Commodore Installer script this time. You have to install this
  122.    by hand.
  123.  
  124.  
  125.    The DOpusLhARexx archive contains the following files:
  126.  
  127.       DOpusLhARexx/DOpusLhARexx.readme
  128.       DOpusLhARexx/Docs/DOpusLhARexx.guide
  129.       DOpusLhARexx/Docs/DOpusLhARexx.doc
  130.       DOpusLhARexx/ARexx/ListLhA.rexx
  131.       DOpusLhARexx/ARexx/GetSizesLhA.rexx
  132.       DOpusLhARexx/ARexx/ExtractFilesLhA.rexx
  133.       DOpusLhARexx/ARexx/SelectFilesLhA.rexx
  134.       DOpusLhARexx/ARexx/DelFilesLhA.rexx
  135.       DOpusLhARexx/ARexx/AddFilesLhA.rexx
  136.       DOpusLhARexx/ARexx/RestoreLhADir.rexx
  137.  
  138.    I would suggest that you create a subdirectory in DOpus: called "ARexx"
  139.    and place the *.rexx files in this directory. Alternatively, you can
  140.    place them into REXX: or even S:
  141.  
  142.    Load up DOpus and go into the configuration editor.
  143.    Select the "Buttons" editor.
  144.  
  145.    Create six new buttons with the following characterisics:
  146.    
  147.       Name               Cmd Type    Command
  148.       ~~~~               ~~~~~~~~    ~~~~~~~
  149.       ListLhA             ARexx       DOpus:ARexx/ListLhA.rexx
  150.       GetSizesLhA         ARexx       DOpus:ARexx/GetSizesLhA.rexx
  151.       ExtLhaFiles         ARexx       DOpus:ARexx/ExtractFilesLhA.rexx
  152.       SelectFilesLhA      ARexx       DOpus:ARexx/SelectFilesLhA.rexx
  153.       DelFilesLhA         ARexx       DOpus:ARexx/DelFilesLhA.rexx
  154.       AddFilesLhA         ARexx       DOpus:ARexx/AddFilesLhA.rexx
  155.       RestoreLhADir       ARexx       DOpus:ARexx/RestoreLhADir.rexx
  156.  
  157.  
  158.    All of these buttons should have no flags set and the default stack,
  159.    priority and close delay values. (Consult the DOpus manual under the
  160.    section "3.5 BUTTONS/EDITOR" if you don't understand what the above
  161.    means)
  162.  
  163.    Fire up your favorite text editor and modify the *.rexx files listed
  164.    above to conform to your system setup. You will only need to modify
  165.    a few variables near the top of each file in the "configuration
  166.    variables section.
  167.  
  168.  
  169.  
  170. ListLhA
  171.  
  172.  
  173.  ListLhA
  174.  ~~~~~~~
  175.  
  176.    What it does:
  177.    ~~~~~~~~~~~~~
  178.  
  179.    The ListLhA script allows the user to list an LhA archive in a buffer
  180.    window.
  181.  
  182.    How to use it:
  183.    ~~~~~~~~~~~~~~
  184.  
  185.    Move into the directory containing the LhA archive you wish to list.
  186.  
  187.    Select an LhA file (only the first selected file is looked at)
  188.  
  189.    Click on the "ListLhA" button.
  190.  
  191.    If the selected file is indeed an LhA archive, the buffer window will clear
  192.    and the archive will be listed in the window.
  193.  
  194.  
  195.  
  196. GetSizesLhA
  197.  
  198.  
  199.  GetSizesLhA
  200.  ~~~~~~~~~~~
  201.  
  202.    What it does:
  203.    ~~~~~~~~~~~~~
  204.  
  205.    The GetSizesLhA script will do a byte count (total) on the files currently
  206.    selected in an LhA archive window. (Much like the DOpus equivalent of
  207.    the "GetSizes" button)
  208.  
  209.    How to use it:
  210.    ~~~~~~~~~~~~~~
  211.  
  212.    Select the file(s) you wish to total in an LhA archive buffer window.
  213.  
  214.    Click on the "GetSizesLhA" button.
  215.  
  216.    You should then see the total byte/file count listed in the status bar.
  217.  
  218.  
  219.  
  220. ExtLhaFiles
  221.  
  222.  
  223.  ExtLhaFiles
  224.  ~~~~~~~~~~~
  225.  
  226.    What it does:
  227.    ~~~~~~~~~~~~~
  228.  
  229.    The ExtLhaFiles script will extract one or more files from an LhA archive
  230.    window into the destination window.
  231.  
  232.    How to use it:
  233.    ~~~~~~~~~~~~~~
  234.  
  235.    Select the file(s) you wish to extract in the LhA archive buffer window.
  236.  
  237.    Click on the "ExtLhaFiles" button.
  238.  
  239.    The script will then extract the selected file(s) to the destination
  240.    window while restoring any path(s) stored in the LhA archive.
  241.  
  242.  
  243.  
  244. SelectFilesLhA
  245.  
  246.  
  247.  SelectFilesLhA
  248.  ~~~~~~~~~~~~~~
  249.  
  250.    What it does:
  251.    ~~~~~~~~~~~~~
  252.  
  253.    The SelectFilesLhA script will allow the user to select file(s) in the
  254.    archive window via a sub-string search.
  255.  
  256.    How to use it:
  257.    ~~~~~~~~~~~~~~
  258.  
  259.    Click on the "SelectFilesLhA" button.
  260.  
  261.    A requester will appear asking you for a sub-string to match on. Type in
  262.    a string that will match all the files you want to select.
  263.  
  264.    All files with the sub-string as part of their path/filename will be
  265.    selected. Additionally, the GetSizesLhA script will be called and
  266.    the byte count (total) of the selected files will appear in the status
  267.    bar.
  268.  
  269.    NOTE: pattern matching is not implemented (yet) so don't try something
  270.          like "*.c". However, if you wish to select ALL files, you CAN
  271.          enter "*" in the requester.
  272.  
  273.  
  274.  
  275. DelFilesLhA
  276.  
  277.  
  278.  DelFilesLhA
  279.  ~~~~~~~~~~~
  280.  
  281.    What it does:
  282.    ~~~~~~~~~~~~~
  283.  
  284.    The DelFilesLhA script will delete the selected file(s) from an archive
  285.    window.
  286.  
  287.    How to use it:
  288.    ~~~~~~~~~~~~~~
  289.  
  290.    Select the file(s) you wish to delete from the LhA archive.
  291.  
  292.    Click on the "DelFilesLhA" button.
  293.  
  294.    A confirmation requester will appear giving you the chance to abort the
  295.    operation. (Once the files are deleted you CANNOT get them back)
  296.  
  297.    After the files have been deleted from the LhA archive, the buffer
  298.    window will be updated by calling the ListLhA script.
  299.  
  300.    If you have deleted ALL the files in the LhA archive, you will be asked
  301.    if you wish to delete the LhA archive. Selecting yes will delete the
  302.    archive and load the original directory back into the window. If you
  303.    choose no, the LhA buffer is left alone and you may add files into the
  304.    empty archive via the "AddFilesLhA" button.
  305.  
  306.  
  307.  
  308. AddFilesLhA
  309.  
  310.  
  311.  AddFilesLhA
  312.  ~~~~~~~~~~~
  313.  
  314.    What it does:
  315.    ~~~~~~~~~~~~~
  316.  
  317.    The AddFilesLhA script allows the user to add one or more files to an
  318.    LhA archive.
  319.  
  320.    How to use it:
  321.    ~~~~~~~~~~~~~~
  322.  
  323.    List an LhA archive you want to add files into.
  324.  
  325.    In the destination window, select the files and/or directories you wish
  326.    to add into the archive.
  327.  
  328.    Click on the "AddFilesLhA" button.
  329.  
  330.    A requester will appear asking you if you wish to store the pathnames of
  331.    the files to be added. Selecting yes will store the paths relative to
  332.    the source directory you have listed in the source window. Selecting
  333.    no will ignore the paths and store the files into the archive as if they
  334.    appeared in one directory.
  335.  
  336.    A second requester will then appear asking you if you wish to add any
  337.    possible sub-directories. If you have selected a directory in the
  338.    source window and you say yes to this requester, LhA will also
  339.    recursively add any files/directories contained within the directorie(s)
  340.    you have selected. Selecting no will only add files contained in the
  341.    selected directorie(s) but no sub-directories below that.
  342.  
  343.    NOTE: Adding possible subdirectories automatically stores the full path
  344.          names in the archive.
  345.  
  346.    The files will be added to the LhA archive and the buffer window will be
  347.    updated by calling the ListLha script.
  348.  
  349.    NOTE: If you click on the "AddFilesLhA" button with no LhA archive listed,
  350.          a requester will appear asking you if you wish to create a new
  351.          LhA archive. Selecting yes will bring up a second requester asking
  352.          you for a filename for the new archive. Enter a filename (with or
  353.          without the ".lha" extension, but excluding the path) noteing that the
  354.          archive will be created in the in-active directory window. (The path
  355.          where the archive is to be created is listed in the requester)
  356.  
  357.          If you have selected one or more files/dirs in the active window,
  358.          they will then be added to the new archive.
  359.  
  360.  
  361.  
  362. RestoreLhADir
  363.  
  364.  
  365.  RestoreLhADir
  366.  ~~~~~~~~~~~~~
  367.  
  368.    What it does:
  369.    ~~~~~~~~~~~~~
  370.  
  371.    The RestoreLhADir script will re-read the directory of the current LhA
  372.    archive listed into the buffer window.
  373.  
  374.    How to use it:
  375.    ~~~~~~~~~~~~~~
  376.  
  377.    Click on the "RestoreLhADir" button.
  378.  
  379.    The directory containing the LhA archive will be read into the buffer
  380.    window.
  381.  
  382.  
  383.  
  384. Bugs
  385.  
  386.  
  387.  Known Bugs
  388.  ~~~~~~~~~~
  389.  
  390.    As far as I know, there are no bugs in these programs. Enforcer was used
  391.    during developement and testing. However, as I was the only person testing
  392.    the scripts, I imagine there maybe some "features" I overlooked...
  393.    
  394.    If you find a problem, please tell me about it (See Author),
  395.    and I'll try to fix it ASAP. Please feel free to send in your suggestions
  396.    for enhancements as well...
  397.  
  398.  
  399.  Limitations
  400.  ~~~~~~~~~~~
  401.  
  402.    DOpus (at this time) only allows file entries of 256 characters. This of
  403.    course limits the scripts to LhA archives with pathnames of about 246
  404.    characters in length.
  405.  
  406.    LhA has path limits similar to those of DOpus as well.
  407.  
  408.  
  409.  
  410. History
  411.  
  412.  
  413.  
  414.  ListLhA.rexx
  415.  ~~~~~~~~~~~~
  416.  
  417.    40.1 - initial quick hack, only displayed files.
  418.  
  419.    40.2 - found bug, was bitten by ARexx quoting so spaces in file names
  420.           screwed up.
  421.         - added true file size in display after figuring out problem above.
  422.         - added two unselectable total entries for new companion script
  423.           GetSizesLhA.rexx.
  424.         - improved messages to user showing just what the hell is going on. :-)
  425.  
  426.    40.3 - added check to ignore file comments in archive.
  427.         - added check to make sure file entry is less than 256 chars.
  428.           (DOpus limit)
  429.  
  430.    40.4 - added code so that DelFilesLhA and AddFilesLhA could call ListLhA
  431.           to update the window as it would be tricky for DelFilesLhA and 
  432.           AddFilesLhA to do this.
  433.  
  434.    40.5 - added code to set the ADDRESS to DOpus if the script was called 
  435.           from someplace else, namely, DelFilesLhA and AddFilesLhA.
  436.         - bug fix. DOpus will only allow 30 characters in the window title,
  437.           I was storing the path AND LhA filename in there (which is fine
  438.           if your lha files are in a top level directory). To fix this,
  439.           I changed the code to store only the LhA filename in the window
  440.           title and added some code to store the path to the LhA archive
  441.           within the directory window itself. By playing with the display
  442.           pens, this entry is "invisible" to the user.
  443.  
  444.  
  445.  GetSizesLhA.rexx
  446.  ~~~~~~~~~~~~~~~~
  447.  
  448.    40.1 - initial version.
  449.         - tried to mimic DOpus 'GetSizes' button.
  450.  
  451.    40.2 - adjusted index calculations due to new info in the footer of the
  452.           directory window.
  453.  
  454.  
  455.  ExtractFilesLhA.rexx
  456.  ~~~~~~~~~~~~~~~~~~~~
  457.  
  458.    40.1 - initial hack after playing with AddCustHandler (gave up...
  459.           for now at least :-) The problem?  Well, AddCustHandler passes
  460.           some arguments, but not quite enough info to be able to extract
  461.           files from the archive. I could get the information I need from
  462.           DOpus itself, however AddCustHandler is 'blocking' DOpus. 
  463.           (ie. DOpus won't respond to ARexx as it's waiting for the
  464.           AddCustHandler script to end/return)  If I can find a clean way
  465.           of using AddCustHandler for Click-M-Click extraction, I'll update
  466.           the archive.
  467.  
  468.    40.2 - added code to allow extracting of all selected files at one time,
  469.           instead of having to open a CON:/LhA for each file. Left original
  470.           code in there for users who like that method. :-)
  471.         - improved messages to user.
  472.         - added check to see if there is a valid destination path.
  473.  
  474.    40.3 - added code to set the ADDRESS to DOpus in case DOpus didn't invoke
  475.           the script.
  476.  
  477.    40.4 - changed code to get the path to the LhA archive from the directory
  478.           window.
  479.  
  480.    40.5 - added TopText call and moved "Busy on" call before requester.
  481.  
  482.    40.6 - bug fixes. added missing quotes and parameters for Status calls.
  483.  
  484.    40.7 - found out that LhA doesn't like certain characters in the file names
  485.           it uses to extract. Added function to change these to wildcards.
  486.  
  487.    40.8 - added code to check the other window if no LhA buffer found in
  488.           current window.
  489.  
  490.  
  491.  AddFilesLhA.rexx
  492.  ~~~~~~~~~~~~~~~~
  493.  
  494.    40.1 - initial version. I said, "What the hell!", might as well be able to
  495.           add and delete files from the archive as well as extract them...
  496.  
  497.    40.2 - added code to get the path to the LhA archive from the directory
  498.           window.
  499.  
  500.    40.3 - added TopText call and moved "Busy on" call before requester.
  501.  
  502.    40.4 - added code to allow the user to create a new archive.
  503.         - added option to recurse subdirectories.
  504.  
  505.    40.5 - found out that LhA doesn't like certain characters in the file names
  506.           it uses to add. Added function to change these to wildcards.
  507.  
  508.    40.6 - added code to list a new archive after creation.
  509.  
  510.  
  511.  DelFilesLhA.rexx
  512.  ~~~~~~~~~~~~~~~~
  513.  
  514.    40.1 - initial version
  515.  
  516.    40.2 - changed the way DelFilesLhA.rexx called ListLhA.rexx as I was
  517.           getting some *very* impressive crashes (continuous yellow screen
  518.           upon reboot!) via 'call ListLhA.rexx'.
  519.         - moved the code to restore DOpus's requester button text from the
  520.           CleanUp function as I don't think it was hitting it.
  521.  
  522.    40.3 - added code to get the path to the LhA archive from the directory
  523.           window.
  524.  
  525.    40.4 - added TopText call and moved "Busy on" call before confirmation
  526.           requester.
  527.         - added code to see if the archive is empty after the delete. If
  528.           it is, the user is given the option of deleting the empty archive.
  529.  
  530.    40.5 - added Busy on call after Request as it seems DOpus turns Busy off
  531.           after the Request.
  532.  
  533.    40.6 - found out that LhA doesn't like certain characters in the file names
  534.           it uses to delete. Added function to change these to wildcards.
  535.         - added check to see if the LhA archive is empty to begin with, if
  536.           so the user is given the option of deleting it.
  537.  
  538.    40.7 - added code to check the other buffer window if no archive is
  539.           detected in the current window.
  540.  
  541.  
  542.  SelectFilesLhA.rexx
  543.  ~~~~~~~~~~~~~~~~~~~
  544.  
  545.    40.1 - initial version
  546.  
  547.    40.2 - added code to call GetFileSizesLha.rexx after file selection to
  548.           show the totals.
  549.         - added ScrollToIndex call so user sees the selection process.
  550.  
  551.    40.3 - added TopText call and moved "Busy on" call before the string
  552.           requester.
  553.     - added special pattern "*" to select all files
  554.  
  555.  RestoreLhADir.rexx
  556.  ~~~~~~~~~~~~~~~~~~
  557.  
  558.    40.1 - initial version
  559.  
  560.    40.2 - added code to check the other buffer window as well.
  561.  
  562.  
  563.  
  564. Author
  565.  
  566.  
  567.  Contacting the Author
  568.  ~~~~~~~~~~~~~~~~~~~~~
  569.  
  570.  
  571.    If you have any comments, suggestions, gripes, or God forbid... bugs,
  572.    Please feel free to contact me at the following places:
  573.  
  574.  
  575.       Snail-Mail:  Geoff Seeley
  576.                    1240 Margaret Place,
  577.                    Duncan, British Columbia
  578.                    Canada
  579.                    V9L 4T6
  580.  
  581.  
  582.       E-Mail:      geoff@softwords.bc.ca                 (InterNet)
  583.  
  584.  
  585.  
  586. ToDos
  587.  
  588.  
  589.  ToDos
  590.  ~~~~~
  591.  
  592.    - finish AddCustHandler for click-m-click extraction of files.
  593.    - add proper pattern matching to SelectFilesLhA.rexx.
  594.    - compile the scripts with the ARexx compiler for speed (Can someone out
  595.      there do this please???)
  596.    - add support for ZIP, TAR, and other archivers.
  597.    - create support functions for DOpus's "AddFile" command (damned thing
  598.      wants the time-stamp in seconds!?)
  599.    - improve the creation of an archive (maybe make "CreateLhA"?)
  600.    - allow operations between archives (ie. list two archives, move files
  601.      between them)
  602.    - make a DOpus help file for the buttons. (haven't used this feature
  603.      yet :-)
  604.    - create non-commented versions for speed
  605.  
  606.